<?php

namespace WebmanGrpc;

use WebmanGrpc\Initializer\Initializer;
use WebmanGrpc\PerformanceMonitor;
use WebmanGrpc\Pool\ConnectionPool;
use WebmanGrpc\Serialization\SerializationOptimizer;
use WebmanGrpc\Memory\MemoryManager;
use WebmanGrpc\Module\ModuleManager;
use WebmanGrpc\Event\EventBus;
use WebmanGrpc\Event\LifecycleEventManager;

/**
 * gRPC扩展包管理器
 * 
 * 这是Webman gRPC扩展包的核心管理类，采用单例模式设计，提供对整个扩展包的统一管理和配置。
 * 它负责初始化和管理所有核心组件，包括连接池、序列化优化器、内存管理器、模块管理器、事件总线等。
 * 
 * 主要功能：
 * 1. 统一初始化所有组件
 * 2. 提供配置管理接口
 * 3. 管理各组件的生命周期
 * 4. 提供性能监控和统计信息
 * 5. 环境检查和版本信息获取
 * 
 * 使用场景：
 * - 在应用启动时初始化gRPC扩展包
 * - 获取各组件实例进行操作
 * - 配置和管理gRPC相关功能
 * - 监控和优化gRPC性能
 * 
 * 使用示例：
 * ```php
 * // 初始化扩展包
 * $manager = GrpcManager::getInstance();
 * $manager->initialize($config);
 * 
 * // 获取连接池
 * $connectionPool = $manager->getConnectionPool();
 * 
 * // 预热连接
 * $manager->warmUpConnections(['localhost:50051']);
 * 
 * // 获取统计信息
 * $stats = $manager->getStats();
 * ```
 * 
 * @author Webman gRPC Team
 * @version 1.1.0
 * @since 1.1.0
 */
class GrpcManager
{
    /**
     * 单例实例
     * 
     * 存储GrpcManager类的唯一实例，实现单例模式。
     * 使用静态变量确保在整个应用程序生命周期中只有一个实例存在。
     * 
     * @var GrpcManager|null 单例实例，初始为null
     */
    protected static ?GrpcManager $instance = null;
    
    /**
     * 初始化状态标志
     * 
     * 标记管理器是否已完成初始化。防止重复初始化导致的问题。
     * 初始化完成后，此标志设为true，后续调用initialize方法将直接返回。
     * 
     * @var bool 初始化状态，默认为false
     */
    protected bool $initialized = false;
    
    /**
     * 配置数组
     * 
     * 存储gRPC扩展包的所有配置选项。这些配置在初始化时设置，
     * 并可以通过getConfig和setConfig方法进行读取和修改。
     * 
     * 配置项包括：
     * - 连接池配置（最大连接数、超时时间等）
     * - 序列化配置（缓存大小、预热类等）
     * - 内存管理配置（内存限制、GC策略等）
     * - 性能监控配置（启用状态、采样率等）
     * 
     * @var array 配置数组，初始为空数组
     */
    protected array $config = [];
    
    /**
     * 构造函数
     * 
     * 私有构造函数，防止直接实例化，确保单例模式的正确实现。
     * 实际获取实例应使用getInstance静态方法。
     * 
     * @access protected
     * @return void
     */
    protected function __construct()
    {
    }
    
    /**
     * 获取单例实例
     * 
     * 实现单例模式的核心方法，返回GrpcManager的唯一实例。
     * 如果实例不存在，则创建一个新实例；否则返回现有实例。
     * 
     * 使用场景：
     * - 在应用启动时获取管理器实例
     * - 在任何需要访问gRPC组件的地方获取管理器
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * ```
     * 
     * @access public
     * @static
     * @return GrpcManager gRPC管理器的单例实例
     */
    public static function getInstance(): GrpcManager
    {
        if (self::$instance === null) {
            self::$instance = new self();
        }
        
        return self::$instance;
    }
    
    /**
     * 初始化gRPC扩展包
     * 
     * 这是扩展包的核心初始化方法，负责初始化所有组件。
     * 它会调用Initializer来初始化各个组件，包括连接池、序列化优化器、内存管理器等。
     * 
     * 初始化过程：
     * 1. 检查是否已初始化，避免重复初始化
     * 2. 设置配置选项
     * 3. 调用Initializer初始化各个组件
     * 4. 标记初始化完成
     * 
     * 使用场景：
     * - 在应用启动时初始化gRPC扩展包
     * - 在测试环境中重置扩展包状态
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * $manager->initialize([
     *     'connection_pool' => [
     *         'max_connections' => 100,
     *         'connect_timeout' => 5.0,
     *     ],
     *     'serialization' => [
     *         'cache_size' => 1000,
     *     ],
     * ]);
     * ```
     * 
     * @param array $config 配置选项，包含连接池、序列化、内存管理等配置
     * @return void
     */
    public function initialize(array $config = []): void
    {
        if ($this->initialized) {
            return;
        }
        
        $this->config = $config;
        
        // 使用初始化器初始化各个组件
        Initializer::initialize($config);
        
        $this->initialized = true;
    }
    
    /**
     * 检查是否已初始化
     * 
     * 返回当前管理器的初始化状态，用于判断扩展包是否已完成初始化。
     * 
     * 使用场景：
     * - 在使用扩展包功能前检查初始化状态
     * - 在测试中验证初始化是否成功
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * if (!$manager->isInitialized()) {
     *     $manager->initialize($config);
     * }
     * ```
     * 
     * @return bool 是否已初始化，true表示已初始化，false表示未初始化
     */
    public function isInitialized(): bool
    {
        return $this->initialized;
    }
    
    /**
     * 获取配置
     * 
     * 获取指定的配置项或全部配置。支持点号分隔的嵌套配置访问。
     * 
     * 配置访问规则：
     * 1. 不提供键名时，返回整个配置数组
     * 2. 提供简单键名时，返回对应的配置值
     * 3. 提供点号分隔的嵌套键名时，递归访问嵌套配置
     * 4. 配置项不存在时，返回指定的默认值
     * 
     * 配置结构示例：
     * ```php
     * [
     *     'connection_pool' => [
     *         'max_connections' => 100,
     *         'timeout' => 5.0,
     *     ],
     *     'serialization' => [
     *         'cache_size' => 1000,
     *     ],
     * ]
     * ```
     * 
     * 使用场景：
     * - 获取特定配置项进行条件判断
     * - 获取全部配置用于调试或日志记录
     * - 动态读取配置参数调整行为
     * 
     * 使用示例：
     * ```php
     * // 获取全部配置
     * $allConfig = $manager->getConfig();
     * 
     * // 获取特定配置项
     * $maxConnections = $manager->getConfig('connection_pool.max_connections');
     * 
     * // 获取不存在的配置项，返回默认值
     * $timeout = $manager->getConfig('timeout', 5.0);
     * 
     * // 在条件判断中使用
     * if ($manager->getConfig('debug.enabled', false)) {
     *     // 启用调试模式
     * }
     * ```
     * 
     * @param string|null $key 配置键，支持点号分隔的嵌套访问，为null时返回所有配置
     * @param mixed $default 默认值，当配置项不存在时返回此值
     * @return mixed 配置值或默认值
     */
    public function getConfig(?string $key = null, $default = null)
    {
        if ($key === null) {
            return $this->config;
        }
        
        // 支持点号分隔的嵌套配置访问
        if (strpos($key, '.') !== false) {
            $keys = explode('.', $key);
            $value = $this->config;
            
            foreach ($keys as $k) {
                if (!is_array($value) || !isset($value[$k])) {
                    return $default;
                }
                $value = $value[$k];
            }
            
            return $value;
        }
        
        return $this->config[$key] ?? $default;
    }
    
    /**
     * 设置配置
     * 
     * 设置指定的配置项或批量设置配置。支持点号分隔的嵌套配置设置。
     * 
     * 配置设置规则：
     * 1. 当键为数组时，执行批量配置合并
     * 2. 当键为字符串且不包含点号时，设置简单配置项
     * 3. 当键为字符串且包含点号时，设置嵌套配置项
     * 4. 对于嵌套配置，自动创建不存在的中间层级
     * 
     * 合并策略：
     * - 批量设置使用array_merge_recursive进行递归合并
     * - 相同键名的数组会进行合并而非覆盖
     * - 非数组值会覆盖原有值
     * 
     * 使用场景：
     * - 动态修改配置
     * - 在运行时调整参数
     * - 根据环境变量更新配置
     * - 插件或模块注册时添加配置
     * 
     * 使用示例：
     * ```php
     * // 设置单个配置项
     * $manager->setConfig('connection_pool.max_connections', 200);
     * 
     * // 设置嵌套配置项
     * $manager->setConfig('services.user.timeout', 5.0);
     * 
     * // 批量设置配置
     * $manager->setConfig([
     *     'connection_pool' => [
     *         'max_connections' => 200,
     *         'connect_timeout' => 10.0,
     *     ],
     *     'debug' => [
     *         'enabled' => true,
     *         'level' => 'verbose',
     *     ],
     * ]);
     * 
     * // 根据环境变量设置配置
     * $manager->setConfig('debug.enabled', getenv('GRPC_DEBUG') === 'true');
     * ```
     * 
     * @param string|array $key 配置键或配置数组
     * @param mixed $value 配置值，当$key为字符串时使用
     * @return void
     */
    public function setConfig($key, $value = null): void
    {
        if (is_array($key)) {
            $this->config = array_merge_recursive($this->config, $key);
        } else {
            // 支持点号分隔的嵌套配置设置
            if (strpos($key, '.') !== false) {
                $keys = explode('.', $key);
                $config = &$this->config;
                
                foreach ($keys as $k) {
                    if (!isset($config[$k]) || !is_array($config[$k])) {
                        $config[$k] = [];
                    }
                    $config = &$config[$k];
                }
                
                $config = $value;
            } else {
                $this->config[$key] = $value;
            }
        }
    }
    
    /**
     * 获取连接池实例
     * 
     * 返回连接池的单例实例，用于管理gRPC连接。
     * 连接池负责创建、复用和管理gRPC连接，提高连接效率和性能。
     * 
     * 连接池功能：
     * - 连接复用：避免频繁创建和销毁连接
     * - 连接管理：自动维护连接的健康状态
     * - 性能优化：减少连接建立的开销
     * - 资源控制：限制最大连接数，防止资源耗尽
     * 
     * 连接池特性：
     * - 单例模式：确保全局只有一个连接池实例
     * - 线程安全：在多进程环境中安全使用
     * - 自动重连：连接断开时自动重新建立
     * - 健康检查：定期检查连接状态，移除无效连接
     * 
     * 使用场景：
     * - 获取连接池进行连接管理
     * - 预热连接或获取连接统计信息
     * - 监控连接池状态和性能
     * - 调试连接相关问题
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * $connectionPool = $manager->getConnectionPool();
     * 
     * // 获取连接
     * $connection = $connectionPool->getConnection('service', ['host' => 'localhost', 'port' => 50051]);
     * 
     * // 获取统计信息
     * $stats = $connectionPool->getStats();
     * 
     * // 预热连接
     * $connectionPool->warmUp(['localhost:50051', 'localhost:50052']);
     * 
     * // 监控连接池状态
     * if ($stats['connections'] > $stats['config']['max_connections'] * 0.8) {
     *     // 连接数接近上限，发出警告
     *     error_log("连接池使用率过高: " . ($stats['connections'] / $stats['config']['max_connections'] * 100) . "%");
     * }
     * ```
     * 
     * @return ConnectionPool 连接池实例
     */
    public function getConnectionPool(): ConnectionPool
    {
        return ConnectionPool::getInstance();
    }
    
    /**
     * 获取性能监控器实例
     * 
     * 返回性能监控器的单例实例，用于监控gRPC请求的性能。
     * 性能监控器负责收集、分析和报告gRPC请求的性能数据。
     * 
     * 性能监控功能：
     * - 请求计时：记录每个请求的开始和结束时间
     * - 性能统计：计算平均响应时间、吞吐量等指标
     * - 错误追踪：记录请求失败的情况和原因
     * - 性能报告：生成详细的性能分析报告
     * 
     * 监控指标：
     * - 响应时间：单个请求的处理时间
     * - 吞吐量：单位时间内处理的请求数
     * - 错误率：失败请求占总请求的比例
     * - 并发数：同时处理的请求数量
     * - 资源使用：CPU、内存等资源消耗情况
     * 
     * 使用场景：
     * - 监控gRPC请求的性能
     * - 生成性能报告
     * - 启用或禁用性能监控
     * - 识别性能瓶颈
     * - 优化系统性能
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * $monitor = $manager->getPerformanceMonitor();
     * 
     * // 开始监控请求
     * $requestId = $monitor->startRequest('service', 'method');
     * 
     * // 结束监控请求
     * $monitor->endRequest($requestId);
     * 
     * // 生成性能报告
     * $report = $monitor->generateReport();
     * 
     * // 获取性能数据
     * $data = $monitor->getPerformanceData();
     * 
     * // 监控性能指标
     * if ($data['average_response_time'] > 1000) {
     *     // 平均响应时间超过1秒，发出警告
     *     error_log("平均响应时间过高: " . $data['average_response_time'] . "ms");
     * }
     * ```
     * 
     * @return PerformanceMonitor 性能监控器实例
     */
    public function getPerformanceMonitor(): PerformanceMonitor
    {
        return PerformanceMonitor::getInstance();
    }
    
    /**
     * 获取模块管理器实例
     * 
     * 返回模块管理器的单例实例，用于管理扩展包的模块。
     * 模块管理器负责注册、注销和管理扩展包的各种模块。
     * 
     * 模块管理功能：
     * - 模块注册：动态注册新的功能模块
     * - 模块注销：安全地移除不需要的模块
     * - 依赖管理：处理模块间的依赖关系
     * - 生命周期管理：控制模块的初始化和销毁
     * 
     * 模块特性：
     * - 热插拔：支持运行时动态加载和卸载模块
     * - 依赖解析：自动解决模块间的依赖关系
     * - 状态管理：跟踪模块的运行状态
     * - 事件驱动：模块间通过事件进行通信
     * 
     * 使用场景：
     * - 注册新的模块
     * - 获取已注册的模块
     * - 管理模块的生命周期
     * - 扩展系统功能
     * - 实现插件化架构
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * $moduleManager = $manager->getModuleManager();
     * 
     * // 注册模块
     * $moduleManager->registerModule('custom_module', new CustomModule());
     * 
     * // 注册带依赖的模块
     * $moduleManager->registerModule('advanced_module', new AdvancedModule(), ['custom_module']);
     * 
     * // 获取模块
     * $module = $moduleManager->getModule('custom_module');
     * 
     * // 获取所有模块状态
     * $status = $moduleManager->getAllModuleStatus();
     * 
     * // 检查模块是否已注册
     * if ($moduleManager->hasModule('custom_module')) {
     *     echo "自定义模块已注册";
     * }
     * 
     * // 卸载模块
     * $moduleManager->unregisterModule('custom_module');
     * ```
     * 
     * @return ModuleManager 模块管理器实例
     */
    public function getModuleManager(): ModuleManager
    {
        return ModuleManager::getInstance();
    }
    
    /**
     * 获取事件总线实例
     * 
     * 返回事件总线的单例实例，用于管理事件的发布和订阅。
     * 事件总线负责事件的分发、监听和处理，实现松耦合的组件通信。
     * 
     * 事件总线功能：
     * - 事件发布：向系统发布各种事件
     * - 事件订阅：注册监听器处理特定事件
     * - 事件分发：将事件分发给所有订阅的监听器
     * - 异步处理：支持异步事件处理机制
     * 
     * 事件特性：
     * - 解耦：组件间通过事件通信，减少直接依赖
     * - 扩展性：易于添加新的事件监听器
     * - 可追溯：记录事件流，便于调试和审计
     * - 优先级：支持监听器优先级，控制处理顺序
     * 
     * 使用场景：
     * - 发布事件
     * - 添加事件监听器
     * - 移除事件监听器
     * - 实现组件间通信
     * - 构建事件驱动架构
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * $eventBus = $manager->getEventBus();
     * 
     * // 添加事件监听器
     * $eventBus->addListener('request.received', function($event) {
     *     echo "请求已接收: " . $event->getData()['request_id'];
     * });
     * 
     * // 添加带优先级的监听器
     * $eventBus->addListener('request.received', function($event) {
     *     // 高优先级处理
     * }, 10);
     * 
     * // 添加一次性监听器
     * $eventBus->addOnceListener('shutdown', function($event) {
     *     // 只执行一次
     *     echo "系统关闭，执行清理操作";
     * });
     * 
     * // 发布事件
     * $eventBus->publish(new Event('request.received', ['request_id' => '123']));
     * 
     * // 移除监听器
     * $listenerId = $eventBus->addListener('request.received', $callback);
     * $eventBus->removeListener($listenerId);
     * ```
     * 
     * @return EventBus 事件总线实例
     */
    public function getEventBus(): EventBus
    {
        return EventBus::getInstance();
    }
    
    /**
     * 获取生命周期事件管理器实例
     * 
     * 返回生命周期事件管理器的单例实例，用于管理gRPC扩展包的生命周期事件。
     * 生命周期事件管理器负责处理扩展包的初始化、运行和销毁过程中的事件。
     * 
     * 生命周期管理功能：
     * - 事件触发：在关键生命周期节点触发事件
     * - 监听器管理：注册和管理生命周期事件监听器
     * - 状态跟踪：跟踪扩展包的当前生命周期状态
     * - 顺序控制：确保事件按正确的顺序触发
     * 
     * 生命周期阶段：
     * - 初始化：扩展包加载和初始化阶段
     * - 运行：扩展包正常运行阶段
     * - 暂停：扩展包暂停服务阶段
     * - 恢复：扩展包从暂停状态恢复阶段
     * - 关闭：扩展包清理和关闭阶段
     * 
     * 使用场景：
     * - 添加生命周期事件监听器
     * - 触发生命周期事件
     * - 管理扩展包的生命周期
     * - 实现资源自动清理
     * - 构建可观测性系统
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * $lifecycleManager = $manager->getLifecycleEventManager();
     * 
     * // 添加初始化事件监听器
     * $lifecycleManager->addListener('initialize', function($event) {
     *     echo "gRPC扩展包初始化完成";
     *     // 执行初始化后的操作
     *     $this->setupMonitoring();
     * });
     * 
     * // 添加关闭事件监听器
     * $lifecycleManager->addListener('shutdown', function($event) {
     *     echo "gRPC扩展包正在关闭";
     *     // 执行清理操作
     *     $this->cleanupResources();
     * });
     * 
     * // 添加错误事件监听器
     * $lifecycleManager->addListener('error', function($event) {
     *     $error = $event->getData()['error'];
     *     echo "发生错误: " . $error->getMessage();
     *     // 记录错误日志
     *     $this->logError($error);
     * });
     * 
     * // 检查当前生命周期状态
     * $currentState = $lifecycleManager->getCurrentState();
     * echo "当前状态: " . $currentState;
     * 
     * // 手动触发生命周期事件（通常由框架自动触发）
     * $lifecycleManager->triggerEvent('custom_event', ['data' => 'value']);
     * ```
     * 
     * @return LifecycleEventManager 生命周期事件管理器实例
     */
    public function getLifecycleEventManager(): LifecycleEventManager
    {
        return LifecycleEventManager::getInstance();
    }
    
    /**
     * 预热连接池
     * 
     * 预热连接池中的连接，提前建立连接以减少首次请求的延迟。
     * 此方法会根据配置中的预热策略，预先创建一定数量的连接。
     * 
     * 预热机制：
     * - 批量创建：一次性创建多个连接，减少开销
     * - 渐进式预热：分批创建连接，避免资源突增
     * - 优先级预热：优先预热常用服务的连接
     * - 失败重试：连接创建失败时自动重试
     * 
     * 预热策略：
     * - 按比例预热：根据连接池大小的一定比例预热
     * - 固定数量预热：预热固定数量的连接
     * - 基于历史数据预热：根据历史使用模式预热
     * - 自适应预热：根据系统负载动态调整预热数量
     * 
     * 使用场景：
     * - 系统启动时预热连接
     * - 流量高峰前预热连接
     * - 提高系统响应速度
     * - 减少冷启动延迟
     * - 优化用户体验
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * 
     * // 基本用法：预热所有连接池
     * $manager->warmUpConnections();
     * 
     * // 预热特定服务的连接池
     * $manager->warmUpConnections('user_service');
     * 
     * // 预热多个服务的连接池
     * $services = ['user_service', 'order_service', 'payment_service'];
     * foreach ($services as $service) {
     *     $manager->warmUpConnections($service);
     * }
     * 
     * // 在系统启动时预热连接
     * // 通常在应用启动脚本中调用
     * $manager->initialize();
     * $manager->warmUpConnections();
     * 
     * // 定时预热连接（例如每天凌晨）
     * $scheduler->schedule('0 2 * * *', function() use ($manager) {
     *     $manager->warmUpConnections();
     * });
     * ```
     * 
     * @param string|null $serviceName 可选，指定要预热的服务名称，为null则预热所有服务
     * @return void
     */
    public function warmUpConnections(?string $serviceName = null): void
    {
        $config = $this->getConfig('connection_pool', []);
        $warmUpEnabled = $config['warm_up_enabled'] ?? false;
        
        if (!$warmUpEnabled) {
            return;
        }
        
        $pool = $this->getConnectionPool();
        $pool->warmUp($serviceName);
    }
    
    /**
     * 预热序列化
     * 
     * 预热序列化器，提前加载和初始化序列化相关的类和资源。
     * 此方法会根据配置中的序列化预热策略，预先加载常用的消息类型。
     * 
     * 序列化预热机制：
     * - 类加载：预先加载常用的消息类和枚举类
     * - 元数据缓存：缓存消息类的元数据，避免反射开销
     * - 序列化器实例化：预先创建序列化器实例
     * - 协议初始化：初始化gRPC协议相关的资源
     * 
     * 预热策略：
     * - 基于配置：根据配置中指定的消息类型预热
     * - 基于历史：根据历史使用数据预热常用消息类型
     * - 全面预热：预热所有已知的消息类型
     * - 按需预热：根据服务依赖关系预热相关消息类型
     * 
     * 序列化优化：
     * - 减少类加载时间：避免运行时动态加载
     * - 减少反射开销：缓存反射结果
     * - 提高序列化速度：预热后的序列化器性能更佳
     * - 降低内存峰值：预先分配内存，避免运行时分配
     * 
     * 使用场景：
     * - 系统启动时预热序列化
     * - 提高序列化性能
     * - 减少首次序列化的延迟
     * - 优化高并发场景
     * - 提升系统整体响应速度
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * 
     * // 基本用法：预热所有序列化器
     * $manager->warmUpSerialization();
     * 
     * // 预热特定消息类型
     * $messageTypes = [
     *     'UserService\UserRequest',
     *     'UserService\UserResponse',
     *     'OrderService\OrderRequest',
     *     'OrderService\OrderResponse'
     * ];
     * $manager->warmUpSerialization($messageTypes);
     * 
     * // 在系统启动时预热序列化
     * // 通常在应用启动脚本中调用
     * $manager->initialize();
     * $manager->warmUpConnections();
     * $manager->warmUpSerialization();
     * 
     * // 根据配置预热
     * $config = $manager->getConfig('serialization');
     * if ($config['warm_up_enabled']) {
     *     $manager->warmUpSerialization($config['warm_up_messages']);
     * }
     * 
     * // 结合服务发现预热
     * $services = $serviceDiscovery->getServices();
     * foreach ($services as $service) {
     *     $messageTypes = $service->getMessageTypes();
     *     $manager->warmUpSerialization($messageTypes);
     * }
     * ```
     * 
     * @param array|null $messageTypes 可选，指定要预热的消息类型列表，为null则根据配置预热
     * @return void
     */
    public function warmUpSerialization(?array $messageTypes = null): void
    {
        $config = $this->getConfig('serialization', []);
        $warmUpEnabled = $config['warm_up_enabled'] ?? false;
        
        if (!$warmUpEnabled) {
            return;
        }
        
        $serializer = $this->getSerializer();
        $serializer->warmUp($messageTypes);
    }
    
    /**
     * 获取统计信息
     * 
     * 获取扩展包各组件的统计信息，用于监控和调试。
     * 统计信息包括连接池状态、序列化性能、内存使用、模块状态等。
     * 
     * 统计信息包括：
     * - connection_pool: 连接池统计（活跃连接数、空闲连接数等）
     * - serialization: 序列化统计（缓存命中率、序列化次数等）
     * - memory: 内存使用统计（当前使用量、峰值使用量等）
     * - modules: 模块状态（已注册模块、模块状态等）
     * - events: 事件统计（事件数量、监听器数量等）
     * - lifecycle_events: 生命周期事件统计
     * - performance: 性能数据（请求时间、吞吐量等）
     * 
     * 统计数据特性：
     * - 实时性：反映当前系统状态
     * - 多维度：从不同角度展示系统状态
     * - 历史对比：支持与历史数据对比
     * - 聚合数据：提供聚合后的统计信息
     * 
     * 监控用途：
     * - 性能监控：监控系统性能指标
     * - 容量规划：根据统计数据规划资源
     * - 故障检测：通过异常数据发现故障
     * - 优化决策：基于数据做出优化决策
     * 
     * 使用场景：
     * - 监控扩展包运行状态
     * - 调试性能问题
     * - 生成运行报告
     * - 容量规划
     * - SLA监控
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * $stats = $manager->getStats();
     * 
     * // 基本用法：获取所有统计信息
     * echo "活跃连接数: " . $stats['connection_pool']['active_connections'];
     * echo "当前内存使用: " . $stats['memory']['current'] . " bytes";
     * echo "平均响应时间: " . $stats['performance']['average_response_time'] . " ms";
     * 
     * // 获取特定类型的统计信息
     * $connectionStats = $manager->getStats('connection_pool');
     * $performanceStats = $manager->getStats('performance');
     * 
     * // 监控连接池状态
     * $totalConnections = $stats['connection_pool']['total_connections'];
     * $activeConnections = $stats['connection_pool']['active_connections'];
     * 
     * if ($activeConnections / $totalConnections > 0.8) {
     *     echo "警告：连接池使用率过高";
     * }
     * 
     * // 监控性能指标
     * $totalRequests = $stats['performance']['total_requests'];
     * $errorCount = $stats['performance']['error_count'];
     * $errorRate = $totalRequests > 0 ? $errorCount / $totalRequests : 0;
     * 
     * if ($errorRate > 0.05) {
     *     echo "警告：错误率过高";
     * }
     * ```
     * 
     * @param string|null $type 可选，指定要获取的统计信息类型，如'connection_pool'、'performance'等，为null则获取所有统计信息
     * @return array 统计信息数组
     */
    public function getStats(?string $type = null): array
    {
        $stats = [
            'connection_pool' => $this->getConnectionPool()->getStats(),
            'serialization' => SerializationOptimizer::getStats(),
            'memory' => MemoryManager::getMemoryStats(),
            'modules' => $this->getModuleManager()->getAllModuleStatus(),
            'events' => $this->getEventBus()->getStats(),
            'lifecycle_events' => $this->getLifecycleEventManager()->getStats(),
            'performance' => $this->getPerformanceMonitor()->getPerformanceData(),
        ];
        
        // 如果指定了类型，只返回该类型的统计信息
        if ($type !== null && isset($stats[$type])) {
            return $stats[$type];
        }
        
        return $stats;
    }
    
    /**
     * 生成性能报告
     * 
     * 生成详细的性能报告，包括连接池、性能监控等方面的数据。
     * 此方法会收集各个组件的性能数据，并生成格式化的报告。
     * 
     * 报告内容：
     * - 系统概览：系统基本信息和整体状态
     * - 连接池分析：连接使用情况、效率分析
     * - 性能指标：请求响应时间、吞吐量等
     * - 错误分析：错误类型、错误率分析
     * - 资源使用：内存、CPU等资源使用情况
     * - 趋势分析：与历史数据对比的趋势
     * 
     * 报告格式：
     * - 文本报告：纯文本格式，易于阅读
     * - HTML报告：富文本格式，包含图表
     * - JSON报告：结构化数据，便于程序处理
     * - PDF报告：专业格式，适合正式报告
     * 
     * 报告用途：
     * - 性能分析：分析系统性能瓶颈
     * - 容量规划：根据性能数据规划资源
     * - 问题诊断：通过报告定位问题
     * - 优化建议：基于报告提供优化建议
     * 
     * 使用场景：
     * - 性能分析
     * - 系统优化
     * - 问题诊断
     * - 定期性能评估
     * - SLA报告
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * 
     * // 基本用法：生成默认格式的性能报告
     * $report = $manager->generatePerformanceReport();
     * echo $report;
     * 
     * // 生成HTML格式的报告
     * $htmlReport = $manager->generatePerformanceReport('html');
     * file_put_contents('performance_report.html', $htmlReport);
     * 
     * // 生成JSON格式的报告
     * $jsonReport = $manager->generatePerformanceReport('json');
     * $data = json_decode($jsonReport, true);
     * 
     * // 生成指定时间范围的报告
     * $report = $manager->generatePerformanceReport('text', [
     *     'start_time' => strtotime('-1 day'),
     *     'end_time' => time()
     * ]);
     * 
     * // 生成包含图表的报告
     * $report = $manager->generatePerformanceReport('html', [
     *     'include_charts' => true,
     *     'chart_types' => ['line', 'bar', 'pie']
     * ]);
     * 
     * // 定期生成报告
     * $scheduler->schedule('0 0 * * *', function() use ($manager) {
     *     $report = $manager->generatePerformanceReport();
     *     $logger->info('每日性能报告', ['report' => $report]);
     *     
     *     // 发送报告到邮箱
     *     $emailService->send([
     *         'to' => 'admin@example.com',
     *         'subject' => '每日gRPC性能报告',
     *         'body' => $report
     *     ]);
     * });
     * 
     * // 自定义报告模板
     * $customReport = $manager->generatePerformanceReport('text', [
     *     'template' => 'custom_template.tpl',
     *     'custom_data' => ['company' => 'Example Corp']
     * ]);
     * ```
     * 
     * @param string $format 报告格式，支持'text'（默认）、'html'、'json'、'pdf'
     * @param array $options 报告选项，包括时间范围、是否包含图表等
     * @return string 格式化的性能报告
     */
    public function generatePerformanceReport(string $format = 'text', array $options = []): string
    {
        $stats = $this->getStats();
        
        // 根据格式生成不同类型的报告
        switch (strtolower($format)) {
            case 'json':
                return $this->generateJsonReport($stats, $options);
            case 'html':
                return $this->generateHtmlReport($stats, $options);
            case 'pdf':
                return $this->generatePdfReport($stats, $options);
            case 'text':
            default:
                return $this->generateTextReport($stats, $options);
        }
    }
    
    /**
     * 生成文本格式的性能报告
     */
    private function generateTextReport(array $stats, array $options): string
    {
        $report = "=== gRPC扩展包性能报告 ===\n";
        $report .= "生成时间: " . date('Y-m-d H:i:s') . "\n\n";
        
        // 连接池统计
        $report .= "连接池统计:\n";
        $report .= "  活跃连接数: " . $stats['connection_pool']['active_connections'] . "\n";
        $report .= "  空闲连接数: " . $stats['connection_pool']['idle_connections'] . "\n";
        $report .= "  总连接数: " . $stats['connection_pool']['total_connections'] . "\n\n";
        
        // 性能统计
        $report .= "性能统计:\n";
        $report .= "  总请求数: " . $stats['performance']['total_requests'] . "\n";
        $report .= "  成功请求数: " . $stats['performance']['successful_requests'] . "\n";
        $report .= "  失败请求数: " . $stats['performance']['failed_requests'] . "\n";
        $report .= "  平均响应时间: " . $stats['performance']['average_response_time'] . "ms\n\n";
        
        // 模块统计
        $report .= "模块统计:\n";
        $report .= "  已加载模块数: " . $stats['modules']['loaded_modules'] . "\n";
        $report .= "  活跃模块数: " . $stats['modules']['active_modules'] . "\n";
        
        return $report;
    }
    
    /**
     * 生成JSON格式的性能报告
     */
    private function generateJsonReport(array $stats, array $options): string
    {
        $report = [
            'title' => 'gRPC扩展包性能报告',
            'generated_at' => date('Y-m-d H:i:s'),
            'stats' => $stats
        ];
        
        return json_encode($report, JSON_PRETTY_PRINT);
    }
    
    /**
     * 生成HTML格式的性能报告
     */
    private function generateHtmlReport(array $stats, array $options): string
    {
        $includeCharts = $options['include_charts'] ?? false;
        
        $html = '<!DOCTYPE html>
<html>
<head>
    <title>gRPC扩展包性能报告</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 20px; }
        .section { margin-bottom: 20px; }
        .section h2 { color: #333; border-bottom: 1px solid #ccc; }
        table { border-collapse: collapse; width: 100%; }
        th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
        th { background-color: #f2f2f2; }
    </style>';
        
        if ($includeCharts) {
            $html .= '<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>';
        }
        
        $html .= '</head>
<body>
    <h1>gRPC扩展包性能报告</h1>
    <p>生成时间: ' . date('Y-m-d H:i:s') . '</p>
    
    <div class="section">
        <h2>连接池统计</h2>
        <table>
            <tr><th>指标</th><th>值</th></tr>
            <tr><td>活跃连接数</td><td>' . $stats['connection_pool']['active_connections'] . '</td></tr>
            <tr><td>空闲连接数</td><td>' . $stats['connection_pool']['idle_connections'] . '</td></tr>
            <tr><td>总连接数</td><td>' . $stats['connection_pool']['total_connections'] . '</td></tr>
        </table>
    </div>
    
    <div class="section">
        <h2>性能统计</h2>
        <table>
            <tr><th>指标</th><th>值</th></tr>
            <tr><td>总请求数</td><td>' . $stats['performance']['total_requests'] . '</td></tr>
            <tr><td>成功请求数</td><td>' . $stats['performance']['successful_requests'] . '</td></tr>
            <tr><td>失败请求数</td><td>' . $stats['performance']['failed_requests'] . '</td></tr>
            <tr><td>平均响应时间</td><td>' . $stats['performance']['average_response_time'] . 'ms</td></tr>
        </table>
    </div>
    
    <div class="section">
        <h2>模块统计</h2>
        <table>
            <tr><th>指标</th><th>值</th></tr>
            <tr><td>已加载模块数</td><td>' . $stats['modules']['loaded_modules'] . '</td></tr>
            <tr><td>活跃模块数</td><td>' . $stats['modules']['active_modules'] . '</td></tr>
        </table>
    </div>
</body>
</html>';
        
        return $html;
    }
    
    /**
     * 生成PDF格式的性能报告
     */
    private function generatePdfReport(array $stats, array $options): string
    {
        // 简化实现，实际项目中可以使用TCPDF等库生成PDF
        $textReport = $this->generateTextReport($stats, $options);
        return "PDF格式报告（简化实现）:\n" . $textReport;
    }
    
    /**
     * 启用性能监控
     * 
     * 启用gRPC请求的性能监控功能。启用后，所有gRPC请求的性能数据将被收集和分析。
     * 性能监控可以帮助识别性能瓶颈和优化系统性能。
     * 
     * 使用场景：
     * - 在生产环境中监控性能
     * - 在测试环境中收集性能数据
     * - 调试性能问题
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * 
     * // 启用性能监控
     * $manager->enablePerformanceMonitoring();
     * 
     * // 执行一些gRPC请求...
     * 
     * // 生成性能报告
     * $report = $manager->generatePerformanceReport();
     * ```
     * 
     * @return void
     */
    public function enablePerformanceMonitoring(): void
    {
        $this->getPerformanceMonitor()->enable();
    }
    
    /**
     * 禁用性能监控
     * 
     * 禁用gRPC请求的性能监控功能。禁用后，将不再收集新的性能数据，
     * 但已收集的数据仍可访问，直到被重置。
     * 
     * 使用场景：
     * - 在生产环境中关闭性能监控以减少开销
     * - 在测试中控制性能监控的范围
     * - 临时停止性能数据收集
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * 
     * // 禁用性能监控
     * $manager->disablePerformanceMonitoring();
     * 
     * // 执行一些gRPC请求（不会被监控）
     * 
     * // 重新启用性能监控
     * $manager->enablePerformanceMonitoring();
     * ```
     * 
     * @return void
     */
    public function disablePerformanceMonitoring(): void
    {
        $this->getPerformanceMonitor()->disable();
    }
    
    /**
     * 清理资源
     * 
     * 清理扩展包占用的资源，包括关闭连接、清空缓存、重置监控数据等。
     * 此方法通常在应用关闭或重启时调用，确保资源得到正确释放。
     * 
     * 清理过程：
     * 1. 触发关闭事件，通知各组件准备关闭
     * 2. 关闭所有连接
     * 3. 清空序列化缓存
     * 4. 重置性能监控数据
     * 
     * 使用场景：
     * - 应用关闭时清理资源
     * - 重启扩展包前清理状态
     * - 测试中重置环境
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * 
     * // 应用关闭时清理资源
     * register_shutdown_function(function() use ($manager) {
     *     $manager->cleanup();
     * });
     * 
     * // 手动清理资源
     * $manager->cleanup();
     * ```
     * 
     * @return void
     */
    public function cleanup(): void
    {
        // 触发关闭事件
        $this->getLifecycleEventManager()->triggerHook('shutdown');
        
        // 关闭所有连接
        $this->getConnectionPool()->closeAll();
        
        // 清空序列化缓存
        SerializationOptimizer::clearCache();
        
        // 重置性能监控
        $this->getPerformanceMonitor()->reset();
    }
    
    /**
     * 获取版本信息
     * 
     * 获取与gRPC相关的版本信息，包括gRPC库版本、Protobuf版本、PHP版本和相关扩展版本。
     * 这些信息对于调试兼容性问题和确保环境正确配置非常有用。
     * 
     * 返回信息包括：
     * - grpc: gRPC库版本
     * - protobuf: Protobuf库版本
     * - php: PHP版本
     * - extension: 相关扩展版本
     *   - grpc: gRPC扩展版本
     *   - protobuf: Protobuf扩展版本
     * 
     * 使用场景：
     * - 检查环境兼容性
     * - 调试版本相关问题
     * - 生成环境报告
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * $versionInfo = $manager->getVersionInfo();
     * 
     * // 输出gRPC版本
     * echo "gRPC版本: " . $versionInfo['grpc'];
     * 
     * // 输出PHP版本
     * echo "PHP版本: " . $versionInfo['php'];
     * 
     * // 输出扩展版本
     * echo "gRPC扩展版本: " . $versionInfo['extension']['grpc'];
     * ```
     * 
     * @return array 包含版本信息的数组
     */
    public function getVersionInfo(): array
    {
        return [
            'grpc' => \Grpc\VERSION ?? 'unknown',
            'protobuf' => \Google\Protobuf\Internal\GPBType::class ? '3.x' : 'unknown',
            'php' => PHP_VERSION,
            'extension' => [
                'grpc' => extension_loaded('grpc') ? phpversion('grpc') : 'not installed',
                'protobuf' => extension_loaded('protobuf') ? phpversion('protobuf') : 'not installed',
            ],
        ];
    }
    
    /**
     * 检查环境
     * 
     * 检查当前环境是否满足运行gRPC扩展包的要求，包括PHP版本、gRPC扩展和Protobuf扩展。
     * 此方法可用于安装前检查或运行时诊断。
     * 
     * 检查项目：
     * - php_version: PHP版本是否满足要求（>=7.4）
     * - grpc_extension: gRPC扩展是否已安装
     * - protobuf_extension: Protobuf扩展是否已安装
     * - overall: 整体环境是否满足要求
     * 
     * 每个检查项包含：
     * - required: 要求值或条件
     * - current: 当前值或状态
     * - satisfied: 是否满足要求
     * 
     * 使用场景：
     * - 安装前检查环境
     * - 运行时诊断问题
     * - 生成环境报告
     * 
     * 使用示例：
     * ```php
     * $manager = GrpcManager::getInstance();
     * $envCheck = $manager->checkEnvironment();
     * 
     * // 检查整体环境是否满足要求
     * if ($envCheck['overall']) {
     *     echo "环境满足要求";
     * } else {
     *     echo "环境不满足要求";
     * }
     * 
     * // 输出详细检查结果
     * foreach ($envCheck as $key => $check) {
     *     if ($key !== 'overall') {
     *         echo "{$key}: " . ($check['satisfied'] ? '满足' : '不满足') . "\n";
     *     }
     * }
     * ```
     * 
     * @return array 包含环境检查结果的数组
     */
    public function checkEnvironment(): array
    {
        $result = [
            'php_version' => [
                'required' => '>=7.4',
                'current' => PHP_VERSION,
                'satisfied' => version_compare(PHP_VERSION, '7.4', '>='),
            ],
            'grpc_extension' => [
                'required' => true,
                'current' => extension_loaded('grpc'),
                'satisfied' => extension_loaded('grpc'),
            ],
            'protobuf_extension' => [
                'required' => true,
                'current' => extension_loaded('protobuf'),
                'satisfied' => extension_loaded('protobuf'),
            ],
        ];
        
        $result['overall'] = $result['php_version']['satisfied'] && 
                           $result['grpc_extension']['satisfied'] && 
                           $result['protobuf_extension']['satisfied'];
        
        return $result;
    }
}